# Настройки

В этой главе перечислены параметры конфигурации, которые можно использовать при вызове scaladoc. 
Некоторую информацию, показанную здесь, можно получить, вызвав scaladoc с флагом `-help`.

### Изменения scaladoc по сравнению со Scala 2

Scaladoc был переписан с нуля, и некоторые функции оказались бесполезными в новом контексте. 
Текущее состояние совместимости со старыми флагами scaladoc 
можно [увидеть здесь](https://github.com/lampepfl/dotty/issues/11907).

### Указание настроек

Настройки scaladoc можно указывать в качестве аргументов командной строки, 
например, `scaladoc -d output -project my-project target/scala-3.0.0-RC2/classes`. 
При вызове из sbt, 
обновите значение `Compile / doc / scalacOptions` и `Compile / doc / target` 
соответственно, например

```sbt
Compile / doc / target := file("output"),
Compile / doc / scalacOptions ++= Seq("-project", "my-project"),
```

### Обзор всех доступных настроек

##### -project

Название проекта. Чтобы обеспечить совместимость с псевдонимами Scala2 с `-doc-title`

##### -project-version

Текущая версия проекта, которая отображается в верхнем левом углу. 
Чтобы обеспечить совместимость с псевдонимами Scala2 с `-doc-version`

##### -project-logo

Логотип проекта, который появляется в верхнем левом углу. 
Чтобы обеспечить совместимость с псевдонимами Scala2 с `-doc-logo`

##### -project-footer

Строковое сообщение, которое отображается в разделе нижнего колонтитула. 
Чтобы обеспечить совместимость с псевдонимами Scala2 с `-doc-footer`

##### -comment-syntax

Язык стилей, используемый для разбора комментариев. 
В настоящее время поддерживается два синтаксиса: `markdown` или `wiki`.
Если настройка отсутствует, по умолчанию - `markdown`.

##### -revision

Редакция (ветвь или ссылка), используемая для создания проекта. 
Полезно с исходными ссылками, чтобы они не всегда указывали на последний мастер, который может быть изменен.

##### -source-links

Ссылки на источники обеспечивают сопоставление между файлом в документации и репозиторием кода.

Примеры исходных ссылок: `-source-links:docs=github://lampepfl/dotty/master#docs`

Принимаемые форматы:

`<sub-path>=<исходная-ссылка> <исходная-ссылка>`

где `<ссылка-источник>` является одним из следующих:
- `github://<organization>/<repository>[/revision][#subpath]` будет соответствовать 
`https://github.com/$organization/$repository/[blob|edit]/$revision[/$subpath]/$filePath[$lineNumber]`, 
если редакция не указана, тогда требуется указать редакцию в качестве аргумента для Scaladoc
- `gitlab://<organization>/<repository>` будет соответствовать 
`https://gitlab.com/$organization/$repository/-/[blob|edit]/$revision[/$subpath]/$filePath[$lineNumber]`, 
если редакция не указана, тогда требуется, 
чтобы редакция была указана как аргумент в Scaladoc
- `<scaladoc-template>`

`<scaladoc-template>` — это формат параметра `doc-source-url` из старого scaladoc. 
ПРИМЕЧАНИЕ. Поддерживаются только шаблоны 
`€{FILE_PATH_EXT}`, `€{TPL_NAME}`, `€{FILE_EXT}`, `€{FILE_PATH}` и `€{FILE_LINE}`.

Шаблон может быть определен только подмножеством источников, 
определенных префиксом пути, представленным `<sub-path>`. 
В этом случае пути, используемые в шаблонах, будут относительными относительно `<sub-path>`.

##### -external-mappings

Сопоставление регулярных выражений, соответствующих записям пути к классам, и внешней документации.

Пример внешнего сопоставления: 

```
-external-mappings:.*scala.*::scaladoc3::https://scala-lang.org/api/3.x/,.*java.*::javadoc::https://docs.oracle.com/javase/8/docs/api/
```

Отображение имеет вид `<regex>::[scaladoc3|scaladoc|javadoc]::<path>`. 
Можно указать несколько сопоставлений, разделенных запятыми, как показано в примере.

##### -social-links

Ссылки на социальные сети. Например:

```
-social-links:github::https://github.com/lampepfl/dotty,discord::https://discord.com/invite/scala,twitter::https://twitter.com/scala_lang
```

Допустимые значения имеют вид: `[github|twitter|gitter|discord]::ссылка`.
Scaladoc также поддерживает `custom::link::white_icon_name::black_icon_name`. 
В этом случае иконки должны находиться в каталоге `images/`.

##### -skip-by-id

Идентификаторы пакетов или классов верхнего уровня, которые следует пропускать при создании документации.

##### -skip-by-regex

Регулярные выражения, соответствующие полным именам пакетов или классов верхнего уровня, которые следует пропускать при создании документации.

##### -doc-root-content

Файл, из которого следует импортировать документацию корневого пакета.

##### -author

Добавление авторов в строку документации `@author Name Surname` по умолчанию 
не будет включено в сгенерированную html-документацию. 
Если необходимо явно пометить классы авторами, scaladoc запускается с данным флагом.

##### -groups

Группировка похожих функций вместе (на основе аннотации `@group`)

##### -private

Показать все типы и члены. Если параметр не указан, показывать только public и protected типы и члены.

##### -doc-canonical-base-url

Базовый URL-адрес для использования в качестве префикса и добавления canonical URL-адресов на все страницы. 
Канонический URL-адрес может использоваться поисковыми системами для выбора URL-адреса, 
который вы хотите, чтобы люди видели в результатах поиска. 
Если не установлено, канонические URL-адреса не генерируются.

##### -siteroot

Каталог, содержащий статические файлы, из которых создается документация. Каталог по умолчанию - `./docs`

##### -no-link-warnings

Подавить предупреждения для двусмысленных или невалидных ссылок. 
Не влияет на предупреждения о некорректных ссылках ресурсов и т. д.

##### -versions-dictionary-url

URL-адрес, указывающий на документ JSON, содержащий словарь: `version label -> documentation location`. 
Файл JSON имеет единственное свойство `versions`, которое содержит словарь, 
связывающий метки определенных версий документации с URL-адресами, указывающими на их `index.html`. 
Полезно для библиотек, которые поддерживают разные версии документации.

Пример JSON-файла:

```json
{
  "versions": {
    "3.0.x": "https://dotty.epfl.ch/3.0.x/docs/index.html",
    "Nightly": "https://dotty.epfl.ch/docs/index.html"
  }
}
```

##### -snippet-compiler

Аргументы компилятора сниппета позволяют настроить проверку типа сниппета.

Этот параметр принимает список аргументов в формате: `args := arg{,args} arg := [path=]flag`,
где `path` - префикс пути к исходным файлам, в которых находятся сниппеты, 
и `flag` - режим проверки типов.

Если `path` отсутствует, аргумент будет использоваться по умолчанию для всех несопоставленных путей.

Доступные флаги: 

- `compile` — включает проверку фрагментов. 
- `nocompile` — отключает проверку сниппетов. 
- `fail` — включает проверку сниппета, утверждает, что сниппет не компилируется.

Флаг `fail` удобен для фрагментов, которые показывают, 
что какое-то действие в конечном итоге завершится ошибкой во время компиляции.

Пример использования:

```
-snippet-compiler:my/path/nc=nocompile,my/path/f=fail,compile
```

Что значит:

- все фрагменты в файлах в каталоге `my/path/nc` вообще не должны рассматриваться снипеттом
- все фрагменты в файлах в каталоге `my/path/f` не должны компилироваться во время компиляции 
- все остальные фрагменты должны компилироваться успешно

##### -scastie-configuration

Определите дополнительную sbt конфигурацию для Scastie фрагментов кода.
Например, когда вы импортируете внешние библиотеки в свои фрагменты,
необходимо добавить соответствующие зависимости.

```
"-scastie-configuration", """libraryDependencies += "org.apache.commons" % "commons-lang3" % "3.12.0""""
```

##### -Ysnippet-compiler-debug

Установка этого параметра заставляет компилятор сниппета печатать сниппет по мере его компиляции (после упаковки).

##### -Ydocument-synthetic-types

Включение в документацию страниц с документацией по встроенным типам (например, `Any`, `Nothing`). 
Этот параметр полезен только для `stdlib`, поскольку scaladoc для Scala 3 использует файлы TASTy. 
Все остальные пользователи не должны касаться этой настройки.


---

**Ссылки:**

- [Scaladoc Guide](https://docs.scala-lang.org/scala3/guides/scaladoc/settings.html)
